home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Night Owl 9
/
Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO
/
015a
/
ben311.zip
/
!BENTXT.EXE
/
BEN.TXT
Wrap
Text File
|
1993-05-15
|
53KB
|
1,457 lines
┌───────────────────────────────────────────────────────────────┐
│ │
│ ╒═════════╗ ╒═════════╗ ╒════╗ ╒════╗ │
│ └┐ ╓───┐ ╚╗ └┐ ╓───┐ ║ │ ╚╗ └┐ ╓╜ │
│ │ ║ │ ║ │ ║ └─╜ │ ╟┐ ╚╗ │ ║ │
│ │ ╚═══╛ ║ │ ╚══╗ │ ║└┐ ╚╗ │ ║ │
│ │ ╓───┐ ║ │ ╓──╜ │ ║ └┐ ╚╗│ ║ │
│ │ ║ │ ║ │ ║ ╒═╗ │ ║ └┐ ╚╡ ║ │
│ ╒╛ ╚═══╛ ╓╜ ╒╛ ╚═══╛ ║ ╒╛ ╚╗ └┐ ║ │
│ └─────────╜ └─────────╜ └────╜ └────╜ │
│ │
│ │
│ │
│ BATCH ENHANCER VERSION 3.11 │
│ │
│ │
│ (C) 1993 by Simvis Soft │
│ All Rights Reserved │
│ │
└───────────────────────────────────────────────────────────────┘
This program is distributed under the Shareware scheme. You are
encouraged to give copies of this program to other computer
users. If you decide to use the program, support the Shareware
marketing concept by becoming a registered user. Read section 6.1
for more details.
─────────────────────────────────────────────────────────────────
Table of Contents
1.1 What is BEN?
1.2 Advantages of BEN over other batch file enhancement programs
1.3 System requirements
1.4 How to install BEN
1.5 How to run BEN
2.1 Quick introduction to BEN's functions
2.2 In-depth discussion of each BEN function
2.3 BEN and environment variables
3.1 BENEdit
3.2 MDESIGN
4.1 Legality information
5.1 How to install ANSI.SYS
5.2 Hints and tips
5.3 Support, bugs report, comments, problems...
6.1 Shareware registration
─────────────────────────────────────────────────────────────────
1.1 What is BEN?
BEN stands for the Batch ENhancer:
*BATCH*
Batch is a very simple yet powerful language DOS uses. Batch
files always end with the extension .BAT. For example, the
AUTOEXEC.BAT in the root directory of your boot disk is a batch
file. Although batch file is very flexible, it has some unwelcome
weaknesses. For example, it cannot get input from the user or
even do simple color-changing.
*ENHANCER*
BEN is developed to compensate for Batch language's weaknesses.
BEN improve many aspects of the current batch file functions, and
it also introduce many new ones. With BEN, you can produce very
useful batch files that can even compete with compiled
programming codes. Yet, BEN is so simple to use that even a
beginner can produce attractive batch files in no time at all.
Once you start using BEN, you will be able to incorporate colors,
sounds, menus, pop-up boxes and a host of other spectacular
features into any batch file that you ever write.
To see an example of what BEN can do for you, run the included
BENDEMO.BAT. Remember to keep in mind that BENDEMO.BAT is only a
batch file!
─────────────────────────────────────────────────────────────────
1.2 Advantages of BEN over other batch file enhancement
programs:
- Large number of powerful functions (42 in total) all
contained into one EXE file.
- All of these functions are very easy to use.
- Comes with BENEdit, a text editor that is tailored for BEN.
With BENEdit, you can edit all your batch files and access
all the features of BEN quickly and easily.
- Optimized for speed.
- Perfect for menu systems.
- Can be used for programming any batch utilities (eg.
INSTALL.BAT).
- Compatible with DOS and Windows.
- Compatible with the network environment. You can now use BEN
to program all the network batch files!
────────────────────────────────────────────────────────────────
1.3 System requirements:
IBM PC/Compatible with 384k+ RAM
PC/MS-DOS 2.1 or higher
Suggested: ANSI.SYS or equivalent
(Note: ANSI.SYS is a driver for the display format designed by
the American National Standards Institute. This driver is
included with all versions of PC/MS-DOS. It is required for the
COLOR function. If ANSI.SYS is not installed in your computer
yet, please refer to section 5.1 for instructions on
installation.)
─────────────────────────────────────────────────────────────────
1.4 How to install BEN:
Use the supplied INSTALL.BAT, or just copy every file into a
directory of your choice.
─────────────────────────────────────────────────────────────────
1.5 How to run BEN:
Format: [d:][pathname] BEN function [params] [functions
[params]...]
Entering the command "BEN" alone in DOS gives you an online help
of BEN's functions. Make sure that the file BEN.HLP is in the
same directory as BEN.EXE. Otherwise, the online help wouldn't
work.
To access a BEN function, you must enter the command "BEN"
followed by the name of the function. Some functions doesn't
require any parameter. An example of this is the Beep function.
You can use it by entering this command into your batch file:
BEN Beep
Other functions of BEN require one or more parameters. For
example, you can clear the screen with the color blue by entering
this command into your
batch file:
BEN Cls Blue
BEN functions can be "stacked" one after another in a command
line. For example, you can group the Beep function and the CLS
function together, one after another. In this case, BEN will
first create a beep, then it will clear the screen with the color
blue:
BEN Beep Cls Blue
When you stack functions together, you may use the "/" separators
if you want. This is not mandatory, but it helps to increase the
readability of your batch file. For example:
BEN Beep / Cls Blue
─────────────────────────────────────────────────────────────────
2.1 Quick introduction to BEN's functions:
Ask: Ask gives the user a choice of keys to press. The
batch file can then interpret the result and act
accordingly.
Beep: Beep simply creates a "beep" sound.
Box: Box creates a Box on the screen.
CleanUp: CleanUp is used at the end of batch files. Its
purpose is cleaning up the mess left behind by
batch routines.
Cls: Cls clears the screen with the specified color.
Color: Color changes the current writing color.
Cursor: Cursor changes the cursor shape.
Delay: Delay pauses the computer for the specified
period of time.
DirDisp: DirDisp displays a directory selection dialog box
where the user is given the opportunity to
choose a file. This is similar to the FILE OPEN
dialog box of Windows.
DirDispA: DirDispA is an advanced version of DirDisp.
Echo: Same as the DOS Echo command.
EGAVGA: EGAVGA switches the EGA 43 / VGA 50 line mode on
or off.
Extract: Extract returns a part of a fully qualified
filename.
Flush: Flush clears the keyboard buffer.
GetCD: GetCD returns the current directory to the batch
file.
GetKey: GetKey pauses the computer until the user presses
a key. This key is returned to the batch file.
GetKeyL: GetKeyL is the same as GetKey, except the key
pressed by the user is converted into lowercase
before it is returned to the batch file.
GetKeyU: GetKeyU is the same as GetKey, except the key
pressed by the user is converted into uppercase
before it is returned to the batch file.
GetLine: GetLine pauses the computer until the user types
a string and presses ENTER. The string is
returned to the batch file.
GetLineL: GetLineL is the same as GetLine, except the
string typed by the user is converted into
lowercase before it is returned to the batch
file.
GetLineU: GetLineU is the same as GetLine, except the
string typed by the user is converted into
uppercase before it is returned to the batch
file.
GetVideo: GetVideo checks what kind of video system is
installed (eg. CGA, VGA) and return the result
to the batch file.
GrowFilledBox: GrowFilledBox displays a filled box on the
screen. The box "grows" out to the screen for a
special effect.
List: List is a file browser.
Locate: Locate moves the cursor to the specified screen
position.
Menu: Menu displays a menu on the screen. The choice
selected by the user is returned to the batch
file.
MenuF: Displays a menu created with MDESIGN, the Menu
Designer, onto the screen.
MenuLCD: Same as Menu, except that the menu is displayed
in black and white for added clarity on LCD
screens.
Message: Message draws a box on the screen and displays
the specified message.
Pause: Pause pauses the computer until the user presses
a key.
Play: Play produces music from the speaker. BEN Play
uses the same statements that the BASIC Play
uses.
SavePath: SavePath is a environment-memory conservation
function.
Scroll: Scrolls a specified region of text up, down, left
or right.
ShadFilledBox: ShadFilledBox displays a filled box on the
screen. This box has a shadow.
Shell: Shell lets the user jump to DOS in the middle of
a batch file.
Sound: Sound produces a sound with the specified
frequency and the specified duration.
T: T uses a data file to run BEN functions more
efficiently.
TitledBox: TitledBox displays a filled box with a title on
the screen.
TransparentBox: TransparentBox shades a specified region of the
screen with the specified color.
Write: Displays a string of text on the screen with the
specified color.
WriteC: Displays a string of text on the screen with the
specified color. The text is centred between the
two sides of the monitor.
WriteV: Displays a string of text on the screen with the
specified color. The text is oriented
vertically.
─────────────────────────────────────────────────────────────────
2.2 In-depth discussion of each BEN function.
BOX FUNCTIONS
─────────────
Box x1 y1 x2 y2 foreground background borderstyle
This function draws an empty box on the screen with an
upper-left corner of (x1,y1) and a lower-right corner of
(x2,y2). Borderstyle can be one of the following:
0 - no border
1 - single line box (─)
2 - double line box (═)
3 - double sides, single top and bottom
4 - single sides, double top and bottom
5 - single left and upper, double lower and right
6 - menu box style
7+ - the border is drawn using the ASCII character
represented by the style value.
The "foreground" and "background" colors can be specified
with special words that BEN recognize. These words are:
Black, Blue, Green, Cyan, Red, Magenta, Brown, LightGray,
DarkGray, LightBlue, LightGreen, LightCyan, LightRed, Light
Magenta, Yellow, and White.
You can also specify the colors with a number if you want.
For example, instead of using the word "Black", you can use
the number 0. Instead of using the word "Blue", you can use
the number 1. And so on.
Examples: BEN Box 1 1 80 25 White Blue 1
BEN Box 10 10 20 20 Yellow Black 3
BEN Box 4 4 8 8 9 2 65
In the first example, BEN draws a white on blue box with a
single-line border, an upper-left corner of (1,1) and a
lower-right corner of (80,25).
In the second example, BEN draws a yellow on black box with
double-lined borders on the sides and single-lined borders
on the top and the bottom. The box has an upper-left corner
of (10,10) and a lower-right corner of (20,20).
In the third example, BEN draws a light-blue on green box
with a border that is drawn by the ASCII character 65 ("A").
The box has an upper-left corner of (4,4) and a lower-right
corner of (8,8).
FilledBox x1 y1 x2 y2 foreground background borderstyle
Same as Box, but the box is filled instead of empty.
Examples: BEN FilledBox 1 1 80 25 White Blue 1
BEN FilledBox 10 10 20 20 Yellow Black 3
BEN FilledBox 4 4 8 8 9 9 2 65
GrowFilledBox x1 y1 x2 y2 foreground background borderstyle
Same as FilledBox, but the box "grows" out onto the screen,
creating a spectacular effect.
Examples: BEN GrowFilledBox 1 1 80 25 White Blue 1
BEN GrowFilledBox 10 10 20 20 Yellow Black 3
BEN GrowFilledBox 4 4 8 8 9 2 65
ShadFilledBox x1 y1 x2 y2 foreground background borderstyle
Same as FilledBox, but the box has a shadow.
Examples: BEN ShadFilledBox 1 1 80 25 White Blue 1
BEN ShadFilledBox 10 10 20 20 Yellow Black 3
BEN ShadFilledBox 4 4 8 8 9 2 65
TitledBox x1 y1 x2 y2 foreground background borderstyle title
Same as FilledBox, but the box has a title. Please note that
tildes (~) in the title are interpreted as spaces.
Examples: BEN TitledBox 1 1 80 25 White Blue 1 Great~box!
BEN TitledBox 10 10 20 20 Yellow Black 3 Another!
BEN TitledBox 4 4 8 8 9 2 65 Best~box~here!
TransparentBox x1 y1 x2 y2 foreground background
Paints the region specified by (x1,y1) - (x2,y2) with the
specified foreground and background colors. Text that are
originally on the screen are not erased; they are just
painted with a new color. Please note that the borderstyle
parameter is not required.
Examples: BEN TransparentBox 1 1 80 25 White Blue
BEN TransparentBox 10 10 20 20 Yellow Black
BEN TransparentBox 4 4 8 8 9 2
INPUT FUNCTIONS
───────────────
Ask options
Waits for the user to press a key that is contained in the
'options' string. The option that the user selects is passed
to the batch file as an errorlevel. (For more details on
errorlevels, please refer to your DOS manual.)
For instance, if the options string is ABCDE and the user
presses the letter C on the keyboard, an errorlevel of 3 is
returned (C is the third character of the string).
Example: @Echo Off
BEN Echo A. Format your hard drive.
BEN Echo B. Diskcopy a disk.
BEN Echo C. Run Windows.
BEN Echo D. Run DOSShell.
BEN Echo E. Play Sim City.
BEN Echo ~
BEN Echo Please make your selection.
BEN Ask ABCDE
If Errorlevel 5 If Not Errorlevel 6 Goto SimCity
If Errorlevel 4 If Not Errorlevel 5 DOSShell
If Errorlevel 3 If Not Errorlevel 4 C:\WIN\WIN
If Errorlevel 2 If Not Errorlevel 3 DiskCopy A: A:
If Errorlevel 1 If Not Errorlevel 2 Format C:
Goto End
:SimCity
C:
CD\SimCity
SimCity
:End
GetKey
Waits for the user to enter a key. This key is returned via
the environment variable %BEN% (or %BEN2%, %BEN3%, etc.
Please refer to section 2.3: "BEN and Environment Variables"
at for further details.)
Example: BEN GetKey
BEN Echo You've pressed the %BEN% key!
GetKeyL
Same as GetKey, but the key is converted into lowercase
before it is returned.
Example: BEN GetKeyL
BEN Echo You've pressed the %BEN% key!
GetKeyU
Same as GetKey, but the key is converted into uppercase
before it is returned.
Example: BEN GetKeyU
BEN Echo You've pressed the %BEN% key!
GetLine
Waits for the user to enter a string. This string is
returned via the environment variable %BEN% (or %BEN2%,
%BEN3%, etc. Please refer to section 2.3: "BEN and
Environment Variables" for further details.)
Example: BEN Echo What's your name?
BEN GetLine
BEN Echo So your name is %BEN%!
GetLineL
Same as GetLine, but the string is converted into lowercase
before it is returned.
Example: BEN Echo What's your name?
BEN GetLineL
BEN Echo So your name is %BEN% in lowercase!
GetLineU
Same as GetLine, but the string is converted into uppercase
before it is returned.
Example: BEN Echo What's your name?
BEN GetLineU
BEN Echo So your name is %BEN% in uppercase!
Menu title choice1 [choice2 choice3...]
Displays a menu on the screen. The choice that is selected
by the user is passed back to the batch file as an
errorlevel. For instance, if the user chooses choice #3, an
errorlevel of 3 is returned. On the other hand, if the user
opts to choose nothing, then an errorlevel of 0 is returned.
Please note that tildes (~) are interpreted as spaces, and
no other function can be stacked after the Menu function is
used. Also, use a minus sign (-) to tell BEN to display a
blank line.
Example: @Echo Off
BEN Menu Please~make~a~selection:
Format~your~hard~drive Diskcopy~a~disk
Run~Windows Run~DOSShell Play~Simcity - Quit
If Errorlevel 6 Goto End
If Errorlevel 5 Goto SimCity
If Errorlevel 4 Goto DOSShell
If Errorlevel 3 Goto Windows
If Errorlevel 2 Goto DiskCopy
If Errorlevel 1 Goto Format
BEN Echo You didn't make a selection!
Goto End
:Format
Format C:
Goto End
:DiskCopy
DiskCopy A: A:
Goto End
:Windows
C:\WIN\WIN
Goto End
:DOSShell
DOSShell
Goto End
:SimCity
C:
CD\SimCity
SimCity
:End
Note: This example is same in functionality as the
example that illustrates the Ask function.
MenuF filename
This function displays a menu created with MDESIGN, the menu
designer. Please refer to section 4.2 for more details.
MenuLCD title choice1 [choice2 choice3...]
Same as Menu, except that the menu is displayed in black and
white for added clarity on LCD screens.
Example: BEN MenuLCD Please~make~a~selection:
Format~your~hard~drive Diskcopy~a~disk Run~Windows
Run~DOSShell Play~Simcity - Quit
Message FUNCTIONS
─────────────────
Echo message [message...]
Works like the DOS Echo function. Everything after the word
Echo is displayed using the current writing color. Thus, no
other functions can be stacked after Echo is used.
If you wish to display a blank line, use the command "BEN
Echo ~". If you wish to display more than one space between
two words, use the tilde (~) as a separator instead. For
example, if you want to display the words "Hello World,
this is the computer speaking.", use the command "BEN Echo
Hello~~~World, this is the computer speaking."
Examples: BEN Echo Hello World!
BEN Echo This is a test!
BEN Echo ~
BEN Echo Hello~~~World, this is the computer
speaking.
List filename title
Acts as a file browser for the file specified by "filename".
Tildes (~) in the title are interpreted as spaces.
Examples: BEN List C:\AUTOEXEC.BAT This~is~your~AUTOEXEC!
BEN List BEN.TXT You~are~reading~BEN.TXT!
Message line1 [line2 line3...]
Pops up a message box onto the screen. Tildes (~) are
interpreted as spaces.
Example: BEN Message Hello~World! This~is~a~test!
This example will pop up a message box on the screen as
shown below:
┌─[_]───────────┐
│ │
│Hello World! │
│This is a test!│
│ │
│ OK ▄ │
│ ▀▀▀▀▀▀ │
└───────────────┘
Write foreground background message
Writes a string onto the screen using the specified
foreground and background colors. Tildes (~) in the message
are interpreted as spaces, and a semi-colon (;) at the end
of the message tells BEN not to wrap to the next line.
The "foreground" and "background" colors can be specified
with special words that BEN recognize. These words are:
Black, Blue, Green, Cyan, Red, Magenta, Brown, LightGray,
DarkGray, LightBlue, LightGreen, LightCyan, LightRed, Light
Magenta, Yellow, and White.
You can also specify the colors with a number if you want.
For example, instead of using the word "Black", you can use
the number 0. Instead of using the word "Blue", you can use
the number 1. And so on.
Examples: BEN Write LightRed Blue Hello~World!
BEN Write LightGreen Black This~is~a~test!;
BEN Write 7 1 Another~test!
In the first example, BEN displays the string "Hello World!"
with a color of light red on blue.
In the second example, BEN displays the string "This is a
test!" with a color of light green on black. Since there is
a semi-colon (;) at the end of the line, BEN doesn't move
the cursor to the beginning of the next line. Instead, BEN
keeps the cursor after the exclamation mark.
In the third example, BEN displays the string "Another
test!" with a color of light gray on blue.
WriteC foreground background message
Same as Write, but the message is centered between the two
sides of the monitor.
Examples: BEN WriteC LightRed Blue Hello~World!
BEN WriteC LightGreen Black This~is~a~test!;
BEN WriteC 7 1 Another~test!
WriteV x y foreground background message
Same as Write, but the message is written as a vertical
column that starts from the position (x,y).
Examples: BEN WriteV 1 1 Yellow Blue An~important~message
BEN WriteV 40 10 LightCyan Black Hello!
BEN WriteV 80 1 7 1 Great!!!
In the first example, BEN displays a yellow on blue vertical
column of string starting from (1,1). The string reads "An
important message".
In the second example, BEN displays a light cyan on black
vertical column of string starting from (40,10). The string
reads "Hello!".
In the third example, BEN displays a light gray on blue
vertical column of string starting from (80,1). The string
reads "Great!!!".
MUSIC FUNCTIONS
───────────────
Beep
Creates a beep sound.
Example: BEN Beep
Play playstring
Plays music using the computer's speaker. The playstring is
exactly the same in format as the BASIC Play statement. Here
is a list of the music commands supported:
ML: legato (8/8 note length)
MN: normal music (7/8 note length)
Ln: length of notes (n=1-64; note length=1/n, eg. n=2 for
1/2 note)
Nn: Note number (n=0-84; 0 is a rest)
On: Octave (n=0-6, default 4)
Pn: Pause (n=1-64; pause length=1/n, eg. n=4 for 1/4 note)
Tn: Tempo (n=32-255, default 120; quarter notes per minute)
[: Move down an octave (min 0)
]: Move up an octave (max 6)
You can also use the actual letters of the notes (C, D, E,
F, G, A, and B). These correspond to "do, re, mi, fa, so,
la, ti". To play a scale, you should use "CDEFGAB]C".
The notes may be followed by dots, by note lengths, and by
sharp or flat symbols (a '+' or '#' for a sharp, a '-' for a
flat). For example, 'D-.' is a dotted D flat. The dot means
that the note will play for half again its usual length.
Dots can be repeated.
You can also use "<" for "[" and ">" for "]" in BEN data
files that are read by BEN's T function. Don't use these in
the command line however, because DOS will interpret them as
redirection signs. If you use them, strange errors may
occur.
Examples: BEN Play O5CDEFGFEDCP1CC
BEN Play ]EEEC
Sound frequency duration
Uses the computer's speaker to produce a tone with the
specified frequency for the specified duration. Frequency is
measured in hertz and duration is measured in milliseconds.
Examples: BEN Sound 1000 1000
BEN Sound 2000 100
SCREEN FUNCTIONS
────────────────
Cls background
Clears the screen with the specified color.
The colors can be specified with special words that BEN
recognize. These words are: Black, Blue, Green, Cyan, Red,
Magenta, Brown, LightGray, DarkGray, LightBlue, LightGreen,
LightCyan, LightRed, Light Magenta, Yellow, and White.
You can also specify the color with a number if you want.
For example, instead of using the word "Black", you can use
the number 0. Instead of using the word "Blue", you can use
the number 1. And so on.
Examples: BEN Cls Blue
BEN Cls Green
Color foreground background
Changes the current writing color. ANSI.SYS must be loaded
for this function to operate.
The "foreground" and "background" colors can be specified
with special words that BEN recognize. These words are:
Black, Blue, Green, Cyan, Red, Magenta, Brown, LightGray,
DarkGray, LightBlue, LightGreen, LightCyan, LightRed, Light
Magenta, Yellow, and White.
You can also specify the colors with a number if you want.
For example, instead of using the word "Black", you can use
the number 0. Instead of using the word "Blue", you can use
the number 1. And so on.
Examples: BEN Color Yellow Blue
BEN Color White Red
BEN Color 7 1
Cursor On/Off/Full/Half
Changes the cursor shape. Use On for a normal cursor (_),
Off for no cursor ( ), Full for a block cursor (█) and Half
for a half-block cursor (▄).
Examples: BEN Cursor Off
BEN Cursor Full
EGAVGA On/Off
Switches the EGA 43 / VGA 50 line mode on or off. If the EGA
43 / VGA 50 line mode is switched on successfully, an
errorlevel of 2 is passed back to the batch file. Otherwise,
an errorlevel of 1 is returned.
Example: @Echo Off
BEN EGAVGA On
If Errorlevel 2 Goto SUCCESS
BEN Echo Sorry. Your computer cannot display in
BEN Echo the EGA 43 or the VGA 50 line mode.
Goto End
:SUCCESS
BEN Cls Blue Color White Blue Locate 30 30
BEN Echo See how big your screen is!
BEN Locate 30 33
Pause
BEN EGAVGA Off
:End
BEN CleanUp
GetVideo
Finds out what kind of video system is installed and returns
the result via %BEN% (or %BEN2%, %BEN3%, etc. Please refer
to section 2.3: "BEN and Environment Variables" for further
details.)
The possible values that can be returned are as follows:
Mono: The computer has a monochrome system.
CGA: The computer has a CGA system.
EGA: The computer has an EGA system.
MCGA: The computer has a MCGA system.
VGA: The computer has a VGA system.
Example: @Echo Off
BEN GetVideo
IF "%BEN%"=="Mono" GOLF /Mono
IF "%BEN%"=="CGA" GOLF /CGA
IF "%BEN%"=="EGA" GOLF /EGA
IF "%BEN%"=="MCGA" GOLF /MCGA
IF "%BEN%"=="VGA" GOLF /VGA
This example shows a batch file that passes different
parameters to the GOLF program (a game?) depending on what
video system the computer has.
Locate x y
Moves the screen cursor to the position (x,y).
Examples: BEN Locate 1 1
BEN Locate 10 15
Scroll x1 y1 x2 y2 direction
Scrolls the text enclosed in the (x1,y1)-(x2,y2) box.
'Direction' can be one of the following: UP, DOWN, LEFT,
RIGHT.
Examples: BEN Scroll 1 1 80 25 UP
BEN Scroll 10 10 20 20 LEFT
MISCELLANEOUS FUNCTIONS
───────────────────────
CleanUp
This function should be called at the end of batch files. It
does four things:
1. Changes the writing color to normal DOS color (same as
calling BEN Color LightGray Black).
2. Changes the cursor to a normal shape (same as calling
BEN Cursor On).
3. Erases all the environment variables that have been
created by BEN (IE. %BEN%, %BEN2%, %BEN3%, etc.)
4. Restores the PATH if the SavePath function had been
called previously. (Please refer to the discussion on
the SavePath function.)
Example: BEN CleanUp
Delay milliseconds
Pauses the computer for the specified number of
milliseconds. (1000 milliseconds = 1 second)
Examples: BEN Delay 1000
BEN Delay 5000
DirDisp directory
Displays a file selection box and allows the user to select
a file. The name of the selected file is stored into %BEN%
(or %BEN2%, %BEN3%, etc. Please refer to section 2.3: "BEN
and Environment Variables" for further details.)
If the user presses ESC and opts not to choose any file,
then %BEN% is set to contain nothing.
Example: BEN DirDisp C:\
IF "%BEN%"=="" Goto Chose_Nothing
BEN Echo You've chosen %BEN%!
Goto End
:Chose_Nothing
BEN Echo You didn't choose any file!
:End
DirDispA directory filemask sortorder returnstring
This is the advanced version of DirDisp. In addition to the
starting directory, you can specify the file mask and the
sorting order.
'Filemask' specifies the types of file you want to display.
For example, if you want to display only EXE files, you can
use a filemask of "*.EXE". If you want to display both EXE
and COM files, you can use a filemask of "*.EXE~*.COM"
[different types of files are separated with tildes (~).]
'Sortorder' specifies the order which DirDispA uses to
display the files. It can be one of the following:
NAME - Files sorted on names in ascending order.
EXTENSION - Files sorted on extensions in ascending
order.
TIME - Files sorted on time from the earliest to the
latest.
SIZE - Files sorted on size from the smallest to the
largest.
X - Files are unsorted.
You can also specify only the first letter of the sortorder
you want. For example, instead of "BEN DirDispA C:\ *.*
NAME", you can use "BEN DirDispA C:\ *.* N". This is not
suggested, however, because it decreases the legibility of
your batch file.
Example: BEN DirDispA C:\ *.BAT~*.SYS~*.EXE EXTENSION
BEN Echo You've picked the file %BEN%!
Extract source mask
This is a function that extracts a certain part of a fully
qualified filename (eg. the result from DirDisp or GetCD)
and stores it into %BEN% (or %BEN2%, %BEN3%, etc. Please
refer to section 2.3: "BEN and Environment Variables" for
further details.)
'Source' specifies the source string from which you want to
extract information. Usually, you should place an
environment variable here.
'Mask' specifies the part of the selected filename you want
BEN to return to you. It can contain one or more letters
which define what BEN should put into %BEN%:
D - Returns only the drive part of the source (eg. C:)
P - Returns only the path part of the source without
the trailing backslash (eg. \TELECOM)
\ - Adds a trailing backslash to the path
N - Returns only the name part of the source
(eg. AUTOEXEC)
. - Adds a dot to the name
E - Returns only the extension part of the source (eg.
BAT)
Example: BEN DirDisp C:\TELECOM
SET SELECT=%BEN%
BEN Extract %SELECT% D
BEN Echo You've selected a file that is located in
drive %BEN%
BEN Extract %SELECT% P
BEN Echo This file has a path (without trailing
backslash) of %BEN%
BEN Extract %SELECT% P\
BEN Echo This file has a path (with trailing
backslash) of %BEN%
BEN Extract %SELECT% N
BEN Echo This file's name is %BEN%
BEN Extract %SELECT% E
BEN Echo And its extension is %BEN%
BEN Extract %SELECT% N.E
BEN Echo Its filename (name+extension) is %BEN%
BEN Extract %SELECT% P\N.E
BEN Echo Its path, name and extension is %BEN%
BEN Extract %SELECT% DP\N.E
BEN Echo This file's full name is %BEN%!
BEN Echo ~
BEN GetCD
BEN Extract %BEN% DRIVE
BEN Echo You're currently in %BEN% drive.
Flush
Clears the keyboard buffer.
Example: BEN Flush
GetCD
Finds out what the current directory is and stores it into
%BEN% (or %BEN2%, %BEN3%, etc. Please refer to section 2.3:
"BEN and Environment Variables" for further details.)
Example: BEN GetCD
BEN Echo Hey man, you're in the %BEN% directory!
Pause
Pauses the computer until the user presses a key.
Example: BEN Pause
SavePath
Saves the PATH environment variable into a file called
SavePath.DAT (this file is stored in the current directory)
and erases the PATH environment variable. Using this
function can free up environment space so that BEN functions
that make use of the environment (eg. GetLine) can function
better. Remember to use the CleanUp function to restore the
PATH upon the completion of the batch file.
Caution: Make sure that you don't change directory after
using SavePath. If you do, you must change back to
the directory where SavePath stores SavePath.DAT
before you run CleanUp.
Example: @Echo Off
BEN SavePath
BEN Echo Your PATH has been saved!
BEN CleanUp
BEN Echo Your PATH is restored!
Shell
"Jumps to DOS". After this function is used, the user can
work in DOS as long as he/she want. He/she can let the batch
file regain control by typing EXIT.
Example: BEN Shell
T filename
Runs all the instructions in the data file. This lets BEN
perform its jobs at a quicker speed.
The data file is just a normal text file (ASCII format). It
can be created with any text editor, such as BENEDIT or the
EDLIN or the EDIT programs included with DOS. The format of
the text file is as follows:
FUNCTIONS
FUNCTIONS
FUNCTIONS
.
.
.
FUNCTIONS
<End of File>
The FUNCTIONS are exactly the same functions as those that
are ran from the command line. For example:
BEN T DATA.DAT
where DATA.DAT contains:
Box 1 1 80 25 Yellow Green 3
Pause
Cursor Off
Cls Blue
<End of File>
is exactly the same as doing this:
BEN Box 1 1 80 25 Yellow Green 3
BEN Pause
BEN Cursor Off
BEN Cls Blue
;This is a comment line.
;Comment lines start with a ';'.
Usually, you should only use the T function when you have a
large quantity of functions that you wish to be processed by
BEN.
Examples: BEN T MYFILE.DAT
BEN T C:\BATCH\INSTRUCT
─────────────────────────────────────────────────────────────────
2.3 BEN and environment variables
Several of BEN's functions (IE. GetKey, GetKeyL, GetKeyU,
GetLine, GetLineL, GetLineU, DirDisp, DirDispA, Extract, GetCD
and GetVideo) return their results using environment variables.
After you use any one of these functions, you can access the data
that BEN returns by calling the variable %BEN%. Just put %BEN% in
your batch file where you want the data to appear. For example,
if you want to get the user's name and re-display it, you can do
the following:
BEN Write White Black Please~enter~your~name:~; GetLine
BEN Write White Black Your~name~is~%BEN%!
If you stack several functions that return data via environment
variables, the first result would be stored into %BEN%, the
second result into %BEN2%, the third into %BEN3%, and so on. For
example, if you want to ask the user to enter two favorite colors
and re-display them, you can do the following:
BEN Write White Black Enter~your~two~favorite~colors:
BEN GetLine GetLine
BEN Write White Black So~they~are:~%BEN%~and~%BEN2%!
Note: At the end of your batch file, you should make a call
to BEN's CleanUp function to erase all the variables
that BEN have created (IE %BEN%, %BEN2%, %BEN3%, etc.)
─────────────────────────────────────────────────────────────────
3.1 BENEdit
BENEdit is a text editor that is included with your BEN package.
With BENEdit, you can create and edit batch files quickly and
easily.
BENEdit and BEN (the Batch ENhancer) work together to provide you
with the perfect environment to do all your batch works. Now, you
can use all your time to productive means by accessing all the
features of BEN inside BENEdit. Just select any BEN function
under the "BEN Functions" menu and answer a few questions.
BENEdit will instantly create the necessary batch program lines
for you. Creating batch files is never so easy before!
To run BENEdit, simply enter this command in DOS:
BENEDIT
If you want to open up a file when BENEdit loads, type BENEDIT
followed by the filename in DOS. For example, if you want to load
the file "QD.BAT", you can enter this command in DOS:
BENEDIT QD
BENEdit is so easy to use that further documentation is not
required. If you have a problem, press F1 in BENEdit to bring up
the context-sensitive help. Make sure that the file BENEDIT.HLP
is in the same directory as BENEDIT.EXE. Otherwise, the context-
sensitive help wouldn't work!
─────────────────────────────────────────────────────────────────
3.2 MDESIGN
Starting from version 3.10, BEN is included with an utility
called MDESIGN. With this program, you can create a menu data
file which can be accessed from BEN. With MDESIGN, many
properties of a menu can be changed easily. Like BENEDIT, it is
very easy to use.
Example: If you have created a menu data file called TEST.MNU,
you can access it from BEN easily with the command
BEN MenuF TEST.MNU
Errorlevels are returned to the calling batch file
similar to the Menu function.
─────────────────────────────────────────────────────────────────
4.1 Legality information
Disclaimer:
Use of this program acknowledges this disclaimer of warranty:
"This program is supplied as is. SIMVIS SOFT disclaims all
warranties, expressed or implied, including, without limitation,
the warranties of merchantability and of fitness of this program
for any purpose. SIMVIS SOFT assumes no liability for damages
directly or consequential, which may result from the use of this
program."
Trademarks:
IBM and PC-DOS are trademarks of International Business Machines
Corporation. MS-DOS, EDLIN, Windows and SMARTDRV are trademarks
of Microsoft Corporation. SPEEDISK is a trademark of Symantec.
SIM CITY is a trademark of Maxis. MAGIK Menu is a trademark of
SIMVIS SOFT.
Acknowledgments:
Doyal Belcher
Edwin Lee
Erik Lee
Jay Norwalk
Jonathan Shek
─────────────────────────────────────────────────────────────────
5.1 How to install ANSI.SYS
a. Find ANSI.SYS from your DOS distribution disk and put it in
the C:\ directory.
b. Add the following line to your CONFIG.SYS (CONFIG.SYS is
located in your C:\ directory) by using BENEdit, EDLIN or
other text editors:
DEVICE=C:\ANSI.SYS
Note: If you don't know where to add this line in
CONFIG.SYS, just add it before the first line.
c. Reboot your computer.
─────────────────────────────────────────────────────────────────
5.2 Hints and Tips:
- If you run out of environment space in the middle of your
batch file, you should use the SavePath function. If this
still doesn't work, increase your environment space by
adding this line to your CONFIG.SYS:
Shell=C:\COMMAND.COM /P /E:4096
If this still doesn't work, increase 4096 to a higher
number.
- Stack functions together to speed up access. For example,
instead of using "BEN Beep" followed by "BEN Pause", use
"BEN Beep Pause" or "BEN Beep / Pause".
Note: Don't stack functions so much that a command line
has more than 120 characters. DOS can only read
about 120 characters at a time.
- Using a disk optimizer on the disk (eg. SPEEDISK) containing
BEN.EXE will speed up the operation of BEN.
- Using a cache on your disk (eg. SMARTDRV, PC-CACHE) will
speed up the operation of BEN.
- In Windows, if you run a batch file that uses blinking
characters, run it inside a full screen, since DOS windows
cannot display blinking characters.
- Use BENEdit to develop all your batch files. It's much
easier to access the features of BEN from BENEdit than
trying to memorize all of them.
- In BENEdit, if you have a mouse, you can find out the
coordinates of any screen positions by:
a. moving your mouse pointer to that position
b. reading the (X,Y) ordered pair at the right side of the
status line.
- If you are trying to develop a password program, you may
discover that BEN doesn't function properly. For example,
this may be the core of your batch file:
BEN Echo Please enter the password:
BEN GetLineU
IF "%BEN%"=="COMPUTER RULES" Goto ACCESS
BEN Echo You have entered the incorrect password. Bye.
Goto End
:ACCESS
BEN Echo You have entered the correct password!
:End
Why doesn't this work? Because GetLine and GetLineU turns
spaces into nulls (ASCII 255) before putting the result into
%BEN%. You can work around this by using the null character
when you test the password. Instead of the command:
IF "%BEN%"=="COMPUTER RULES" Goto ACCESS
^
SPACE
You should use the command:
IF "%BEN%"=="COMPUTER RULES" Goto ACCESS
^
NULL
You can enter a null character from any text editor (eg.
BENEdit) by holding the ALT-key, pressing the keys "2", "5",
"5" on the numeric keypad, and releasing the ALT-key.
- To create blinking text, use a light background. For
example, if you want to display a blinking yellow message on
a blue background, use a foreground color of yellow and a
background color of light blue:
BEN Write Yellow LightBlue Hello~World!
- Files browsed with List can be zoomed, moved and sized by
using the F5, CTRL-F5 and ALT-F5 keys respectively. Menu
boxes can also be moved with the CTRL-F5 key.
- If you use the Box, FilledBox, GrowFilledBox or
ShadFilledBox functions, you can create good-looking borders
by specifying an ASCII number as the borderstyle. For
example, to create a box with a border made up of "_", enter
the following command:
BEN Box 1 1 80 25 LightGray Blue 251
- If you port some BASIC Play statements to BEN's Play
commands, remember to turn all "<"'s to "["'s and all ">"'s
to "]"'s. Or, put all the statements into a data file and
use BEN's T function to access them.
- Use the Color command before the Locate command.
- Examining the BENDEMO files is a good way to learn BEN
functions.
- If you are a programmer, use BEN to develop INSTALL.BATs for
your programs.
- If you work in a network, use BEN to develop network batch
utilities.
- Register BEN and get the bonus BENMOUSE program. With
BENMOUSE, you can make use of the mouse in your batch files.
─────────────────────────────────────────────────────────────────
5.3 Support, bug reports, comments, problems...
If you need technical support, feel that this manual is
inadequate, or uncover any bugs, please contact me:
Simon Lee
7905 Bayview Ave.
Unit 1019
Thornhill Ontario
Canada
L3T 7N3
Phone: (416) 882-2514
Fax: (416) 882-2527
Comments are extremely welcome.
─────────────────────────────────────────────────────────────────
6.1 Shareware Registration
BEN is NOT free software. BEN is NOT public domain software. BEN
is shareware: you are expected to pay a registration fee to the
author of this program if you find it useful. You are allowed to
use BEN for free within a trial period of 60 days. After 60 days,
if you continue to use BEN, you must register.
There are three editions of BEN available for registration:
A> Personal Edition - $39
With registration, you get the following:
- Complete BEN package on a disk:
- BEN.EXE with your specified registration name
encoded into the code.
- BENMOUSE.EXE (a bonus version of BEN that has the
ability to make use of mouses) with your specified
registration name encoded into the code.
- BENEDIT.EXE with your specified registration name
encoded into the code.
- MDESIGN.EXE with your specified registration name
encoded into the code.
- All other BEN-related files.
- Next version of the complete BEN package on a disk free
of charge.
- One printed manual that covers all aspects of BEN.
- Free technical support.
B> Programmer's Edition - $99
With registration, you get the following:
- Complete BEN package on a disk:
- BEN.EXE with your specified registration name
encoded into the code.
- BENMOUSE.EXE (a bonus version of BEN that has the
ability to make use of mouses) with your specified
registration name encoded into the code.
- BENEDIT.EXE with your specified registration name
encoded into the code.
- MDESIGN.EXE with your specified registration name
encoded into the code.
- All other BEN-related files.
- Next version of the complete BEN package on a disk free
of charge.
- One printed manual that covers all aspects of BEN.
- A distribution license. With this license, you are
permitted to use BEN to create batch utilities that you
can distribute, royalty-free.
- Free technical support.
C> Business Edition - $199
With registration, you get the following:
- Complete BEN package on a disk:
- BEN.EXE with your specified registration name
encoded into the code.
- BENMOUSE.EXE (a bonus version of BEN that has the
ability to make use of mouses) with your specified
registration name encoded into the code.
- BENEDIT.EXE with your specified registration name
encoded into the code.
- MDESIGN.EXE with your specified registration name
encoded into the code.
- All other BEN-related files.
- All future versions of the complete BEN package on a
disk free of charge.
- Five sets of printed manuals that covers all aspects of
BEN.
- A site license for unlimited number of users on a LAN.
- A distribution license. With this license, you are
permitted to use BEN to create batch utilities that you
can distribute, royalty-free.
- Free technical support.
To order, please send $39, $99 or $199 (depending on which
edition you want) + $5 Postage/Handling to the following address:
Simon Lee
7905 Bayview Ave.
Unit 1019
Thornhill Ontario
Canada
L3T 7N3
Notes:
- Do specify the registration name (eg. Mr. Bill Smith, ABC
Company).
- Do specify the size of the disk you want (IE. 5.25" or 3.5")
- Pay in cash or cheque.
- Make all cheques payable to Simon Lee.
- Pay in Canadian currency if ordered from Canada. Pay in US
currency if ordered from US or other countries.
* You can simplify the registration process by selecting the
"Register" option under the system menu in BENEdit.